---
slug: /api/return-values
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Return Values

In addition to returning basic types (string, boolean, ...), Dagger Functions can also return any of Dagger's core types, such as `Directory`, `Container`, `Service`, `Secret`, and many more.

This opens powerful applications to Dagger Functions. For example, a Dagger Function that builds binaries could take a directory with the source code as argument and return another directory (a "just-in-time" directory) containing just binaries or a container image (a "just-in-time" container) with the binaries included.

:::note
If a function doesn't have a return type annotation, it'll be translated to the [dagger.Void][void-type] type in the API.

[void-type]: https://docs.dagger.io/api/reference/#definition-Void
:::

## String return values

Here is an example of a Dagger Function that returns operating system information for the container as a string:

<Tabs groupId="language">
<TabItem value="Go">
```go file=./snippets/functions/arguments-container/go/main.go
```
</TabItem>
<TabItem value="Python">
```python file=./snippets/functions/arguments-container/python/main.py
```
</TabItem>
<TabItem value="TypeScript">
```typescript file=./snippets/functions/arguments-container/typescript/index.ts
```
</TabItem>
<TabItem value="PHP">
```php file=./snippets/functions/arguments-container/php/src/MyModule.php
```
</TabItem>
<TabItem value="Java">
```java file=./snippets/functions/arguments-container/java/src/main/java/io/dagger/modules/mymodule/MyModule.java
```
</TabItem>
</Tabs>

Here is an example call for this Dagger Function:

```shell
dagger call os-info --ctr=ubuntu:latest
```

The result will look like this:

```shell
Linux buildkitsandbox 6.1.0-22-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.94-1 (2024-06-21) x86_64 x86_64 x86_64 GNU/Linux
```

## Integer return values

Here is an example of a Dagger Function that returns the sum of two integers:

<Tabs groupId="language">
<TabItem value="Go">
```go file=./snippets/functions/arguments-return-values-integer/go/main.go
```
</TabItem>

<TabItem value="Python">
```python file=./snippets/functions/arguments-return-values-integer/python/main.py
```
</TabItem>

<TabItem value="TypeScript">
```typescript file=./snippets/functions/arguments-return-values-integer/typescript/index.ts
```
</TabItem>

<TabItem value="PHP">
```php file=./snippets/functions/arguments-return-values-integer/php/src/MyModule.php
```
</TabItem>

<TabItem value="Java">
:::note
You can either use the primitive `int` type or the boxed `java.lang.Integer` type.
:::

```java file=./snippets/functions/arguments-return-values-integer/java/src/main/java/io/dagger/modules/mymodule/MyModule.java
```
</TabItem>
</Tabs>

Here is an example call for this Dagger Function:

```shell
dagger call add-integer --a 1 --b 2
```

The result will look like this:

```shell
3
```

## Floating-point number return values

Here is an example of a Dagger Function that returns the sum of two floating-point numbers:

<Tabs groupId="language">
<TabItem value="Go">
```go file=./snippets/functions/arguments-return-values-float/go/main.go
```
</TabItem>

<TabItem value="Python">
```python file=./snippets/functions/arguments-return-values-float/python/main.py
```
</TabItem>

<TabItem value="TypeScript">

:::note
There's no `float` type keyword in TypeScript because the type keyword `number` already supports floating point numbers.

To declare a `float` return type on the function signature, import `float` from `@dagger.io/dagger` and use it as return type.
The imported `float` type is a `number` underneath, so you can return it as you would return a regular type `number`.
:::

```typescript file=./snippets/functions/arguments-return-values-float/typescript/index.ts
```
</TabItem>

<TabItem value="PHP">
```php file=./snippets/functions/arguments-return-values-float/php/src/MyModule.php
```
</TabItem>

<TabItem value="Java">
:::note
You can either use the primitive `float` type or the boxed `java.lang.Float` type.
:::

```java file=./snippets/functions/arguments-return-values-float/java/src/main/java/io/dagger/modules/mymodule/MyModule.java
```
</TabItem>
</Tabs>

Here is an example call for this Dagger Function:

```shell
dagger call add-float --a 1.4 --b 2.7
```

The result will look like this:

```shell
4.1
```

## Directory return values

Directory return values might be produced by a Dagger Function that:

- Builds language-specific binaries
- Downloads source code from git or another remote source
- Processes source code (for example, generating documentation or linting code)
- Downloads or processes datasets
- Downloads machine learning models

Here is an example of a Go builder Dagger Function that accepts a remote Git address as a `Directory` argument, builds a Go binary from the source code in that repository, and returns the build directory containing the compiled binary:

<Tabs groupId="language">
<TabItem value="Go">
```go file=./snippets/functions/return-values-directory/go/main.go
```
</TabItem>
<TabItem value="Python">
```python file=./snippets/functions/return-values-directory/python/main.py
```
</TabItem>
<TabItem value="TypeScript">
```typescript file=./snippets/functions/return-values-directory/typescript/index.ts
```
</TabItem>
<TabItem value="PHP">
```php file=./snippets/functions/return-values-directory/php/src/MyModule.php
```
</TabItem>
<TabItem value="Java">
```java file=./snippets/functions/return-values-directory/java/src/main/java/io/dagger/modules/mymodule/MyModule.java
```
</TabItem>
</Tabs>

Here is an example call for this Dagger Function:

```shell
dagger call go-builder --src=https://github.com/golang/example#master:/hello --arch=amd64 --os=linux
```

Once the command completes, you should see this output:

```shell
_type: Directory
entries:
    - hello
```

This means that the build succeeded, and a `Directory` type representing the build directory was returned. This `Directory` is called a "just-in-time" directory: a dynamically-produced artifact of a Dagger pipeline.

## File return values

Similar to just-in-time directories, Dagger Functions can produce just-in-time files by returning the `File` type.

Just-in-time files might be produced by a Dagger Function that:

- Builds language-specific binaries
- Combines multiple input files into a single output file, such as a composite video or a compressed archive

Here is an example of a Dagger Function that accepts a filesystem path or remote Git address as a `Directory` argument and  returns a ZIP archive of that directory:

<Tabs groupId="language">
<TabItem value="Go">
```go file=./snippets/functions/return-values-file/go/main.go
```
</TabItem>
<TabItem value="Python">
```python file=./snippets/functions/return-values-file/python/main.py
```
</TabItem>
<TabItem value="TypeScript">
```typescript file=./snippets/functions/return-values-file/typescript/index.ts
```
</TabItem>
<TabItem value="PHP">
```php file=./snippets/functions/return-values-file/php/src/MyModule.php
```
</TabItem>
<TabItem value="Java">
```java file=./snippets/functions/return-values-file/java/src/main/java/io/dagger/modules/mymodule/MyModule.java
```
</TabItem>
</Tabs>

Here is an example call for this Dagger Function:

```shell
dagger call archiver --src=https://github.com/dagger/dagger#main:./docs/current_docs/quickstart
```

Once the command completes, you should see this output:

```shell
_type: File
name: out.zip
size: 13744
```

This means that the build succeeded, and a `File` type representing the ZIP archive was returned.

## Container return values

Similar to directories and files, just-in-time containers are produced by calling a Dagger Function that returns the `Container` type. This type provides a complete API for building, running and distributing containers.

Just-in-time containers might be produced by a Dagger Function that:

- Builds a container
- Minifies a container
- Downloads a container image from a running registry
- Exports a container from Docker or other container runtimes
- Snapshots the state of a running container

You can think of a just-in-time container, and the `Container` type that represents it, as a build stage in Dockerfile. Each operation produces a new immutable state, which can be further processed, or exported as an OCI image. Dagger Functions can accept, return and pass containers between themselves, just like regular variables.

Here's an example of a Dagger Function that returns a base `alpine` container image with a list of additional specified packages:

<Tabs groupId="language">
<TabItem value="Go">
```go file=./snippets/functions/return-values-container/go/main.go
```
</TabItem>
<TabItem value="Python">
```python file=./snippets/functions/return-values-container/python/main.py
```
</TabItem>

<TabItem value="TypeScript">
```typescript file=./snippets/functions/return-values-container/typescript/index.ts
```
</TabItem>
<TabItem value="PHP">
```php file=./snippets/functions/return-values-container/php/src/MyModule.php
```
</TabItem>
<TabItem value="Java">
```java file=./snippets/functions/return-values-container/java/src/main/java/io/dagger/modules/mymodule/MyModule.java
```
</TabItem>
</Tabs>

Here is an example call for this Dagger Function:

```shell
dagger call alpine-builder --packages=curl,openssh
```

Once the command completes, you should see this output:

```shell
_type: Container
defaultArgs:
    - /bin/sh
entrypoint: []
mounts: []
platform: linux/amd64
user: ""
workdir: ""
```

This means that the build succeeded, and a `Container` type representing the built container image was returned.

:::note
When calling Dagger Functions that produce a just-in-time artifact, you can use the Dagger CLI to add more functions to the pipeline for further processing - for example, inspecting the contents of a directory artifact, exporting a file artifact to the local filesystem, publishing a container artifact to a registry, and so on. This is called ["function chaining"](./index.mdx#chaining), and it is one of Dagger's most powerful features.
:::

## Chaining

So long as a Dagger Function returns an object that can be JSON-serialized, its state will be preserved and passed to the next function in the chain. This makes it possible to write custom Dagger Functions that support function chaining in the same style as the Dagger API.

Here is an example module with support for function chaining:

<Tabs groupId="language">
<TabItem value="Go">
```go file=./snippets/functions/return-values-chaining/go/main.go
```
</TabItem>
<TabItem value="Python">
```python file=./snippets/functions/return-values-chaining/python/main.py
```
</TabItem>
<TabItem value="TypeScript">
```typescript file=./snippets/functions/return-values-chaining/typescript/index.ts
```
</TabItem>
<TabItem value="PHP">
```php file=./snippets/functions/return-values-chaining/php/src/MyModule.php
```
</TabItem>
<TabItem value="Java">
```java file=./snippets/functions/return-values-chaining/java/src/main/java/io/dagger/modules/mymodule/MyModule.java
```
</TabItem>
</Tabs>

And here is an example call for this module:

```shell
dagger call with-name --name=Monde with-greeting --greeting=Bonjour message
```

The result will be:

```shell
Bonjour, Monde!
```
